5.1 Interface Options

These options control the process of locating the appropriate file to browse, and the appearance of the browsing interface.

woman-man.conf-path

A list of strings representing directories to search and/or files to try for a man configuration file. The default is

          ("/etc" "/usr/local/lib")

[for GNU/Linux and Cygwin respectively.] A trailing separator (/ for UNIX etc.) on directories is optional and the filename matched if a directory is specified is the first to match the regexp man.*\.conf. If the environment variable MANPATH is not set but a configuration file is found then it is parsed instead (or as well) to provide a default value for woman-manpath.

woman-manpath

A list of strings representing directory trees to search for Unix manual files. Each element should be the name of a directory that contains subdirectories of the form man?, or more precisely subdirectories selected by the value of woman-manpath-man-regexp. Non-directory and unreadable files are ignored. This can also contain conses, with the car indicating a PATH variable component mapped to the directory tree given in the cdr.

If not set then the environment variable MANPATH is used. If no such environment variable is found, the default list is determined by consulting the man configuration file if found. By default this is expected to be either /etc/man.config or /usr/local/lib/man.conf, which is controlled by the user option woman-man.conf-path. An empty substring of MANPATH denotes the default list. Otherwise, the default value of this variable is

          ("/usr/man" "/usr/local/man")

Any environment variables (names of which must have the Unix-style form $NAME, e.g. $HOME, $EMACSDATA, $EMACS_DIR, regardless of platform) are evaluated first but each element must evaluate to a single directory name. Trailing /s are ignored. (Specific directories in woman-path are also searched.)

On Microsoft platforms I recommend including drive letters explicitly, e.g.

          ("C:/Cygwin/usr/man" "C:/usr/man" "C:/usr/local/man")

The MANPATH environment variable may be set using DOS semi-colon-separated or Unix-style colon-separated syntax (but not mixed).

woman-manpath-man-regexp

A regular expression to match man directories under the woman-manpath directories. These normally have names of the form man?. Its default value is "[Mm][Aa][Nn]", which is case-insensitive mainly for the benefit of Microsoft platforms. Its purpose is to avoid directories such as cat?, ., .., etc.

woman-path

A list of strings representing specific directories to search for Unix manual files. For example

          ("/emacs/etc")

These directories are searched in addition to the directory trees specified in woman-manpath. Each element should be a directory string or nil, which represents the current directory when the path is expanded and cached. However, the last component (only) of each directory string is treated as a regexp (Emacs, not shell) and the string is expanded into a list of matching directories. Non-directory and unreadable files are ignored. The default value on MS-DOS is

          ("$DJDIR/info" "$DJDIR/man/cat[1-9onlp]")

and on other platforms is nil.

Any environment variables (names of which must have the Unix-style form $NAME, e.g. $HOME, $EMACSDATA, $EMACS_DIR, regardless of platform) are evaluated first but each element must evaluate to a single directory name (regexp, see above). For example

          ("$EMACSDATA")

or equivalently

          ("$EMACS_DIR/etc")

Trailing /s are discarded. (The directory trees in woman-manpath are also searched.) On Microsoft platforms I recommend including drive letters explicitly.

woman-cache-level

A positive integer representing the level of topic caching:

1. cache only the topic and directory lists (uses minimal memory, but not recommended);
2. cache also the directories for each topic (faster, without using much more memory);
3. cache also the actual filenames for each topic (fastest, but uses twice as much memory).

The default value is currently 2, a good general compromise. If the woman command is slow to find files then try 3, which may be particularly beneficial with large remote-mounted man directories. Run the woman command with a prefix argument or delete the cache file woman-cache-filename for a change to take effect. (Values < 1 behave like 1; values > 3 behave like 3.)

woman-cache-filename

Either a string representing the full pathname of the WoMan directory and topic cache file, or nil. It is used to save and restore the cache between Emacs sessions. This is especially useful with remote-mounted man page files! The default value of nil suppresses this action. The “standard” non-nil filename is ~/.wmncach.el. Remember that a prefix argument forces the woman command to update and re-write the cache.

woman-dired-keys

A list of dired mode keys to be defined to run WoMan on the current file, e.g. ("w" "W") or any non-nil atom to automatically define w and W if they are unbound, or nil to do nothing. Default is t.

woman-imenu-generic-expression

Imenu support for Sections and Subsections: an alist with elements of the form (MENU-TITLE REGEXP INDEX)—see the documentation for imenu-generic-expression. Default value is

          ((nil "\n\\([A-Z].*\\)" 1)  ; SECTION, but not TITLE
           ("*Subsections*" "^   \\([A-Z].*\\)" 1))

woman-imenu

A boolean value that defaults to nil. If non-nil then WoMan adds a Contents menu to the menubar by calling imenu-add-to-menubar.

woman-imenu-title

A string representing the title to use if WoMan adds a Contents menu to the menubar. Default is "CONTENTS".

woman-use-topic-at-point

A boolean value that defaults to nil. If non-nil then the woman command uses the word at point as the topic, without interactive confirmation, if it exists as a topic.

woman-use-topic-at-point-default

A boolean value representing the default value for woman-use-topic-at-point. The default value is nil. [The variable woman-use-topic-at-point may be let-bound when woman is loaded, in which case its global value does not get defined. The function woman-file-name sets it to this value if it is unbound.]

woman-uncompressed-file-regexp

A regular match expression used to select man source files (ignoring any compression extension). The default value is "\\.\\([0-9lmnt]\\w*\\)" [which means a filename extension is required].

Do not change this unless you are sure you know what you are doing!

The SysV standard man pages use two character suffixes, and this is becoming more common in the GNU world. For example, the man pages in the ncurses package include toe.1m, form.3x, etc.

Please note: an optional compression regexp will be appended, so this regexp must not end with any kind of string terminator such as $ or \\'.

woman-file-compression-regexp

A regular match expression used to match compressed man file extensions for which decompressors are available and handled by auto-compression mode. It should begin with \\. and end with \\' and must not be optional. The default value is "\\.\\(g?z\\|bz2\\|xz\\)\\'", which matches the gzip, bzip2, and xz compression extensions.

Do not change this unless you are sure you know what you are doing!

[It should be compatible with the car of jka-compr-file-name-handler-entry, but that is unduly complicated, includes an inappropriate extension (.tgz) and is not loaded by default!]

woman-use-own-frame

If non-nil then use a dedicated frame for displaying WoMan windows. This is useful only when WoMan is run under a window system such as X or Microsoft Windows that supports real multiple frames, in which case the default value is non-nil.